home *** CD-ROM | disk | FTP | other *** search
/ Java Programmer's Toolkit / Java Programmer's Toolkit.iso / applets / collectn / map.jav < prev    next >
Text File  |  1995-10-14  |  4KB  |  133 lines
  1. /*
  2.   File: Map.java
  3.  
  4.   Originally written by Doug Lea and released into the public domain. 
  5.   Thanks for the assistance and support of Sun Microsystems Labs, Agorics 
  6.   Inc, Loral, and everyone contributing, testing, and using this code.
  7.  
  8.   History:
  9.   Date     Who                What
  10.   24Sep95  dl@cs.oswego.edu   Create from collections.java  working file
  11.  
  12. */
  13.   
  14. package collections;
  15.  
  16. import java.util.Enumeration;
  17. import java.util.NoSuchElementException;
  18.  
  19. /**
  20.  *
  21.  * Maps maintain keyed elements. Any kind of Object 
  22.  * may serve as a key for an element.
  23.  *
  24.  * @author Doug Lea
  25.  * @version 0.93
  26.  *
  27.  * <P> For an introduction to this package see <A HREF="index.html"> Overview </A>.
  28. **/
  29.  
  30.  
  31. public interface Map extends Collection {
  32.  
  33. /**
  34.  * Report whether the Map COULD include k as a key
  35.  * Always returns false if k is null
  36. **/
  37.  
  38.   public boolean     canIncludeKey(Object k);
  39.  
  40. /**
  41.  * Report whether there exists any element with Key key.
  42.  * @return true if there is such an element
  43. **/
  44.  
  45.   public boolean     includesKey(Object key);
  46.  
  47. /**
  48.  * Report whether there exists a (key, value) pair
  49.  * @return true if there is such an element
  50. **/
  51.  
  52.   public boolean     includesAt(Object key, Object value);
  53.  
  54.  
  55. /**
  56.  * Return an enumeration that may be used to traverse through
  57.  * the keys (not elements) of the collection. The corresponding
  58.  * elements can be looked at by using at(k) for each key k. For example:
  59.  * <PRE>
  60.  * Enumeration keys = amap.keys();
  61.  * while (keys.hasMoreElements()) {
  62.  *   Object key = keys.nextElement();
  63.  *   Object value = amap.at(key)
  64.  * // ...
  65.  * }
  66.  * </PRE>
  67.  * @return the enumeration
  68. **/
  69.  
  70.   public CollectionEnumeration keys();
  71.  
  72.  
  73. /**
  74.  * Return the element associated with Key key. 
  75.  * @param key a key
  76.  * @return element such that includesAt(key, element)
  77.  * @exception NoSuchElementException if !includesKey(key)
  78. **/
  79.  
  80.   public Object      at(Object key)
  81.                        throws NoSuchElementException;
  82.  
  83. /**
  84.  * Return a key associated with element. There may be any
  85.  * number of keys associated with any element, but this returns only
  86.  * one of them (any arbitrary one), or null if no such key exists.
  87.  * @param element, a value to try to find a key for.
  88.  * @return k, such that 
  89.  * <PRE>
  90.  * (k == null && !includes(element)) ||  includesAt(k, element)
  91.  * </PRE>
  92. **/
  93.  
  94.   public Object      aKeyOf(Object element);
  95.  
  96. /**
  97.  * Construct a new Map that is a clone of self except
  98.  * that it includes the new pair. If there already exists
  99.  * another pair with the same key, the new collection will
  100.  * instead have one with the new elment.
  101.  * @param the key for element to add
  102.  * @param the element to add
  103.  * @return the new Map c, for which:
  104.  * <PRE>
  105.  * c.at(key).equals(element) &&
  106.  * foreach (k in keys()) c.at(v).equals(at(k))
  107.  * foreach (k in c.keys()) (!k.equals(key)) --> c.at(v).equals(at(k))
  108.  * </PRE>
  109. **/
  110.  
  111.  
  112.   public Map  puttingAt(Object key, Object element) 
  113.                           throws IllegalElementException;
  114.  
  115. /**
  116.  * Construct a new Map that is a clone of self except
  117.  * that it does not include the given key.
  118.  * It is NOT an error to exclude a non-existent key.
  119.  * @param key the key for the par to remove
  120.  * @param element the element for the par to remove
  121.  * @return the new Map c, for which:
  122.  * <PRE>
  123.  * foreach (v in c.keys()) includesAt(v, at(v)) &&
  124.  * !c.includesKey(key) 
  125.  * </PRE>
  126. **/
  127.   public Map  removingAt(Object key);
  128.  
  129.  
  130. }
  131.  
  132.  
  133.